package com.lion.common.modules.file.web.api;

import com.chris.dev.base.libs.v1.http.params.ResourceParam;
import com.chris.dev.base.libs.v1.http.results.ListResult;
import com.chris.dev.base.libs.v1.http.results.ResourceResult;
import com.lion.common.modules.file.web.model.result.Base64Result;
import com.lion.common.spring.annotations.ResponseBodyPack;
import com.lion.common.spring.openapi.AccessToken;
import com.lion.common.spring.openapi.ApiGroup;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.multipart.MultipartFile;

/**
 * @author Chris Chan
 * Create On 2025/8/26 下午7:03
 * Use for: 文件系统 API
 * Explain:
 */
@AccessToken
@ResponseBodyPack
@ApiGroup("file")
@Tag(name = "文件系统", description = "文件系统相关接口，需要具有访问权限")
public interface FileApi {

    /**
     * 文件上传
     * 保留原文件名
     *
     * @param file
     * @return
     */
    @Operation(summary = "文件上传(保留原文件名)", description = "保留原文件名")
    @PostMapping("upload")
    ResourceResult upload(MultipartFile file);

    /**
     * 文件上传
     * 带文件命名
     *
     * @param fileName
     * @param file
     * @return
     */
    @Operation(summary = "文件上传(改名)", description = "带文件命名")
    @PostMapping("uploadWithName")
    ResourceResult uploadWithName(String fileName, MultipartFile file);

    /**
     * 文件上传
     * 可选重命名模式
     *
     * @param mode
     * @param file
     * @return
     */
    @Operation(summary = "文件上传(可选重命名)", description = "可选重命名模式</br>参数说明: mode=1 保留文件名，其他值生成随机文件名")
    @PostMapping(value = "uploadFile")
    ResourceResult uploadFile(int mode, MultipartFile file);

    /**
     * 多文件上传
     *
     * @param mode
     * @param files
     * @return
     */
    @Operation(summary = "多文件上传", description = "可选重命名模式</br>参数说明: mode=1 保留文件名，其他值生成随机文件名")
    @PostMapping("uploadFiles")
    ListResult<ResourceResult> uploadFiles(int mode, MultipartFile... files);

    /**
     * 以Base64方式上传文件
     *
     * @param param
     * @return
     */
    @Operation(summary = "文件上传(Base64)", description = "以Base64方式上传文件")
    @PostMapping("uploadBase64")
    ResourceResult uploadBase64(ResourceParam param);


    /**
     * 文件转Base64
     *
     * @param file
     * @return
     */
    @Operation(summary = "文件转Base64", description = "文件转Base64")
    @PostMapping("fileToBase64")
    Base64Result fileToBase64(MultipartFile file);
}
